---
title: Pan Plugin
description: Enables users to scroll the document by clicking and dragging with a hand tool in Vue.
searchable: true
---

# Pan Plugin

The Pan Plugin provides a "hand tool" that allows users to navigate the PDF by clicking and dragging the document within the viewport. This offers an intuitive alternative to using scrollbars, especially on touch devices.

## Installation

This plugin depends on the `Viewport` and `Interaction Manager` plugins. You must install all three packages.

```sh npm2yarn
npm install @embedpdf/plugin-pan @embedpdf/plugin-viewport @embedpdf/plugin-interaction-manager
````

## Registration

Import `PanPluginPackage` and its dependencies, and add them to the `plugins` array. The Pan plugin is registered after its dependencies.

```typescript {5, 14, 17-19}
import { createPluginRegistration } from '@embedpdf/core'
// ... other imports
import { ViewportPluginPackage } from '@embedpdf/plugin-viewport/vue'
import { InteractionManagerPluginPackage } from '@embedpdf/plugin-interaction-manager/vue'
import { PanPluginPackage } from '@embedpdf/plugin-pan/vue'

const plugins = [
  // ... other essential plugins
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(RenderPluginPackage),

  // Register dependencies first
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(InteractionManagerPluginPackage),

  // Register and configure the pan plugin
  createPluginRegistration(PanPluginPackage, {
    defaultMode: 'mobile', // Automatically enable pan as default on touch devices
  }),
]
```

## Usage

The plugin works by registering a "pan" interaction mode. You can build UI to toggle this mode on and off using the `usePan` composable.

### Building a Pan Tool Button

The `usePan` composable provides the reactive `isPanning` state and a `provides` object with methods to control the pan mode. The `isPanning` ref is perfect for providing visual feedback in your UI, such as highlighting the tool's button when it is active.

```vue
<script setup lang="ts">
import { usePan } from '@embedpdf/plugin-pan/vue';

const { provides: pan, isPanning } = usePan();
</script>

<template>
  <button
    v-if="pan"
    @click="pan.togglePan"
    :class="{ 'active': isPanning }"
  >
    Hand Tool
  </button>
</template>
```

### Using `GlobalPointerProvider`

For a smooth panning experience, it's crucial that the viewer can track mouse movements even when the cursor moves outside the boundaries of the viewport. The `GlobalPointerProvider` component, exported from the `Interaction Manager` plugin, solves this by capturing events globally.

You should wrap your `<Viewport>` component with `<GlobalPointerProvider>` to enable this behavior.

```vue {2, 5, 9}
<script setup lang="ts">
import { GlobalPointerProvider } from '@embedpdf/plugin-interaction-manager/vue';
</script>
<template>
  <GlobalPointerProvider>
    <Viewport>
      <Scroller>{/* ... */}</Scroller>
    </Viewport>
  </GlobalPointerProvider>
</template>
```

## Live Example

This example includes a toolbar button that toggles the pan mode. Click the hand tool icon to activate it, then click and drag the document to scroll.

import { PanExample } from '../code-examples/pan-example';

<PanExample />

## API Reference

### Configuration (`PanPluginConfig`)

| Option | Type | Description |
| :--- | :--- | :--- |
| **`defaultMode`** | `'never' \| 'mobile' \| 'always'` | Determines if pan should be the default interaction mode. \<br /\>- **`never`**: Another mode (like text selection) is default. \<br /\>- **`mobile`**: Pan is the default mode only on touch-enabled devices. \<br /\>- **`always`**: Pan is the default mode on all devices. \<br /\>**Default**: `'mobile'` |

### Composable: `usePan()`

Connects your component to the pan plugin's state and functions.

#### Returns

| Property | Type | Description |
| :--- | :--- | :--- |
| **`isPanning`** | `Ref<boolean>` | A reactive boolean that is `true` when the pan mode is active. |
| **`provides`** | `Ref<PanCapability \| null>` | A ref object with methods to control the pan mode, or `null` if the plugin is not ready. |

#### `PanCapability` Methods

| Method | Description |
| :--- | :--- |
| **`enablePan()`** | Activates the pan mode. |
| **`disablePan()`** | Deactivates pan mode and returns to the default interaction mode. |
| **`togglePan()`** | Toggles the pan mode on or off. |
| **`makePanDefault()`** | Sets the pan mode as the new default interaction for the viewer session. |